Astro Docsの日本語翻訳メモ

2025年9月30日

Astroはドキュメントに関するドキュメントもかなり充実していて、読めば分かるが、充実している分全部読むのも大変、時間が空くとルールを忘れてしまうし、かつ見落としもあるので、メモとして残しておく。

正直わざわざ翻訳しなくても、ブラウザの翻訳機能使えばいいんじゃないと思うこともあるけど、やっぱりめんどくさいし、自分は機械翻訳された日本語には、多分一生馴染めないと思っている。精度に限界があるとかそういう話ではなく、感覚的な話。

そのほかにも自分が翻訳に参加するモチベーションはいろいろある。

• 翻訳を通してそのツールについて詳しくなれること
• ちょっとした英語の勉強にもなること
• 貢献につながること（少なくとも将来の自分のためにはなる）
• コミュニティとのつながり

ステップ1：準備

環境準備

基本的なことだけどまずは本家のリポジトリをForkして、自分のスペースに持ってきておく。

フォークしたリポジトリを手元にクローンして、pnpm installとpnpm devを実行してローカルサーバで見れればOK。

Discord

翻訳作業を始める前にAstroのDiscordサーバーに参加しておくといいと思う。

翻訳をするためのdocs-i18nチャンネルがあって、さらにその中にi18n-crew-jaというサブチャンネル？がある。

日本語の翻訳をしている人たちが集まっていて、日本語でいろいろ質問できたり、PRのレビュー依頼したりとかできる。

できれば、他の方と翻訳しているページが重複するのは避けたほうがいいので、やりまーすとかって宣言するのが望ましいと思う。

ステップ2：翻訳対象のページを探す

どのページを翻訳するかを探すためのツールもある。素晴らしい。

• Translation Tracker：すべてのページの翻訳状況（更新が必要かなど）が一目で分かる。Gitの履歴を元に自動で更新されているらしい。すごい。日本語もまだまだ更新が必要なものがある
• GitHubのgood first issueを確認する：「good first issue」というのは最初の一歩としてちょうどいいイシューとしてラベル付けされる。
• Discordのdocs-i18チャンネルを確認する：毎週火曜日に前の週に英語ページで更新があったページのアナウンスがあるので、そこから選んでみる
• GitHubのPRを確認する：日本語訳のPRは「i18n(ja)」というタイトルをつけるルールになっているの、レビュー待ちのPRがないかチェックしておこう

最初はいきなり大きなものをやるのではなく、小さいものをピックアップして、作業からPRがマージされるところまでをやって、流れを把握するのがいいと思う。

ちなみに私が最初にやったのはサンプルコードの間違いを直すもので、翻訳ですらなかった。イシューですでに対応方針も決まっていたので、やってみた。

他の参考情報として「What to translate」というセクションも用意されている。

ドキュメントに沿ってカテゴリ分けされていて、各カテゴリの閲覧数、メンテナンスコスト、ページサイズが書いてある。

閲覧数が多いページは優先的に翻訳した方がいいけど、専門用語が多いとその分、翻訳も難しくなったりするので、自分にあったページを選んでみるといい。

まれに、公開サイトのページの一番下に「このページを翻訳」というボタンがない場合があるらしく、そのページは翻訳の準備が整っていないので、翻訳作業の対象から外しているということらしい。私はみたことがないけど。

ステップ3：ファイル構造を理解する

今だとCodexとかClaude Codeで/initコマンドを打てば、ある程度まとめてくれるが、Astroドキュメントの翻訳対象となるコンテンツは、おもに3種類ある。

• ドキュメントページ（.mdx）
  • 場所: src/content/docs/ja/
  • メインで翻訳対象となる各ページの主要なコンテンツ。英語版はenディレクトリにあり、これを元にjaディレクトリ内に日本語版のファイルを作成・更新する。
• UIで再利用される文字列（.yml）
  • 場所: src/content/i18n/ja.yml
  • サイドバー内にある「Sponsored by」のような、サイトのUIで共通して使われる短いラベルで、キーと翻訳された文字列のペアで記述する。
• サイドバーのナビゲーションラベル（.ts）
  • 場所: src/content/nav/ja.ts
  • 左サイドバーに表示されるセクション名などのラベル。navDictionary()ヘルパーメソッドを使って定義する。

ステップ4：翻訳時の重要ルールと注意点

翻訳作業する際の、守るべきルールがいくつかある。これもAIに読ませて最終チェックする時のガードにするといいと思う。日本語特有のルールもある。

現状も完全に一貫性があるわけではないけど、細かいところは他の日本語ページを参考にしながらやってみるといい。

• frontmatterの扱い:
  • titleとdescriptionの「値」のみを翻訳する。
  • layoutやi18nReadyなどの「プロパティ名」は翻訳しない
• Asides（囲み記法）:
  • :::tipのような注意書きブロックのこと
  • [オンラインプレビュー]のような角括弧内のカスタムタイトルと、ブロック内のテキストのみを翻訳する
  • :::tipや:::cautionといった種類名は翻訳しない
• カスタムコンポーネント:
  • コンポーネントの開始タグと終了タグの間に挟まれたコンテンツ（<slot/>にあたる部分）を翻訳する
  • slot="headerApp"のようなスロット名は翻訳しない
• コードサンプル:
  • コード内のコメントは翻訳することが推奨されている
  • 変数名や関数名を翻訳するかどうかは、各言語チームの判断に委ねられているが、変数名や関数名を日本語にすることはない
  • たとえば文章的な文字列を変数に値として入れたりしている場合、私は基本翻訳するようにしている
• 品質と一貫性:
  • 英語版を正として、内容の構造や意味を変えてはいけない
  • 英語版のドキュメント自体に改善が必要だと感じた場合は、まず英語版の修正PRを別途作成する

ちなみに言語ごとにローカルルールもあり日本語翻訳ガイド用意されている。迷うような箇所は大抵カバーされていて素晴らしい。

あと、日本語だけtextlintによるチェックができるように用意されている。エラーとして出してもらえると、修正すべきかどうか迷う余地がなくなるのでありがたい。

ステップ5：Pull Requestの作成とレビュー

翻訳が完了したら、GitHubでPRを作成します。PRのタイトルはi18n(ja): <更新内容>のように、言語がわかる形式にしておく。これも過去のPRを見ておけばなんとなく分かる。

以下のような点に注意する。

• 小さいPRの方が、レビューが早く進むので、できるだけPRは小さく保つ。一度に2〜3ページ以上の大きな変更はしない
• レビューがスムーズにするために、PRのコメントに、翻訳で難しかった点や質問などを書いておくといい

（自分が出すPRは1ファイルだけど、変更点が多いことが多く、ごめんなさいと思っています）

PRはテンプレートがある。テンプレートを編集モードでみると分かるが、いろいろと見えないコメントを書いてくれているので、それに従えばOK。

初めてコントリビュートするときは、Discordのユーザー名を書いておくと、Discord上でメンション飛ばしてくれる。コミュニティとして本当に素晴らしいなと思う。よく考えられてる。

PRを作成すると、気付いた人が誰かしらレビューしてくれるけど、なかなか始まらない場合は、Discordのスレッドで共有するといい。

他人のPRのレビューは誰でもやっていいことになっているみたい。というより、誤字脱字がある、読んでいて不自然な表現がある、用語の不一致などがある、などを見てもらえるとだいぶありがたい。

レビューして問題がなければ、「LGTM!」（Looks Good To Me）とコメント残しておくと、コアメンバーが良きタイミングでマージしてくれる。